Libris Britannia 4/science library(b).zip/science library(b)/ENGINEER/1740.ZIP/PWRSTAR.HLP

Text File | 1989-01-11 | 19KB | 368 lines

                            PwrStar 2.17 Help File
     Copyright (c) 1986, 1987, 1988 HyperStuffWare, All Rights Reserved

PwrStar  is a user friendly  program  dedicated to numerical analysis of user
provided data.  Each option is selected by merely touching the first key of a
function name  such as [K]bdInput.  The  purpose of the current version is to
provide a polynomial best  fit to a given set of data by the method  of least
squares.  The user may interactively choose up to a 14th order polynomial fit
and get an automatic display of the input and the fitted curve.

By fitting a large order least squares polynomial to your data  PwrStar gives
you more power than other available  programs  which let you select from some
predefined number of equations.   For  example, exponential  and  logarithmic
curve fits can be easily performed.  PwrStar gives you a numerical evaluation
of the goodness  of the  fit and  then allows you to graphically display  the
results.  This often times  brings out  otherwise hidden  characterisitics of
the fitted curve.

There is a  definite  sequence of  events that should be  followed to get the
most out of the program, but you are  encouraged to improvise.   For example:

1.  Use [K]bdInput to enter the data from the keyboard or [F]ileInput to read
    a previously  generated ASCII  file with the input.  When using files not
    generated by PwrStar, the format must be the same as provided in the file
    SAMPLE.DAT

2.  Use [S]ave to save the results on disk before starting any modifications.

3.  Use [E]dit to verify that the input was correct and modify, delete or add
    additional points.

4.  Use [S]ave again to save the results.

5.  Use [L]sqFit  to calculate  a polynomial fit of up to 14th order.  A good
    rule of thumb is to use the lowest order  polynomial that provides a good
    fit.   The correlation  coefficient calculated  by [L]sqFit indicates how
    good the fit really is with 1.0 being an exact fit.


6.  Use [G]raph to display the input data and goodness of the polynomial fit.

7.  Repeat steps 5 and 6 until satisfied with the results.

8.  Use [P]rint  to get a  hardcopy of the input data, the calculated results,
    the coefficient of the polynomial, and the correlation coefficient.

9.  Once the  polynomial fit is defined, [I]nterpolate can be used to find new
    values for F(X) at a given value of X.  Version 1.2 now also gives you the
    normalized values Xn and Fn(Xn) as previously described.


OPTION [K]bdInput: This is  the most basic  option of PwrStar used to enter a
list of points from the keyboard for display  & analysis.  The first input is
the independent variable X and the second is the independent F(X) variable as
a function of X; thus F(X).  Starting with version 1.36 you can now select an
[A]utomatic  point sequencing for entry (recommeded) or [M]anually  selecting
the sequence.

SubOption [M]anual Sequence.   After selecting this option you will be  asked
first enter a point number, then X and F(X).  The process continues until you
enter C/R  at the point number prompt.  When  you are prompted for X and F(X),
hitting a C/R  enters a value of  0.0 for each  one.  You can enter up to 300
points in any order and to correct a mistake simply reenter the same point. By
allowing points to be entered in any  order, you  have greater flexibility to
fix mistakes as you enter the data.  However, it is imperative that no points
be left undefined or you  will get unpredictable results.  For example if you
enter 8 points in the following order:  1,2,3,3,10,7,5,6,6,9  points number 4
and 8 will be undefined or have some strange values  in them.  PwrStar should
catch the error and  tell you to fix  the problem with  [E]dit PRIOR to doing
anything else....WITH GREAT POWER COMES GREAT RESPONSIBILITY....

SubOption [A]utomatic Sequence.  After  selecting this option you'll be asked
to enter X and  F(X) pairs very much like  the [M]anual option.  However, you
will not be prompted for the point number which is automatically provided and
you must wait until after entering  ALL the data to correct any mistakes with
the [E]dit option.  After each point is entered you will be asked  whether to
continue or stop.  Hitting Y or C/R continues the input while N or ESC stops.

OPTION [F]ileInput:  This option  allows you to enter data from a previously
defined ASCII file.  The file may be  generated with the [S]ave option after
first entering from the keyboard or with your  favorite wordprocessor/editor.
If the file is not generated by PwrStar then it must have the same format as
shown below and in SAMPLE.DAT

3 = Total Number of Points
I    X       F(X)
1  0.05    1.2545
2  0.10    2.3810
3  0.2     4.5678

When [F]ileInput is selected, the program checks to see if it exists and beeps
if it does not.  If no extension is given then '.DAT' is assumed.

OPTION [D]ir:  Is  used to provide a  directory listing of files that match a
given template.  Wild characters and path names are ok.  If  your provide the
path name only, then PwrStar will  change its default  directory to  your new
name if its legal.  Please note that PwrStar must be in the same directory as
the *.BGI files when the [G]raph option is run for the first time.

OPTION [E]dit:  Used to interactively delete, insert, or delete points from a
set of data that have been entered.  You have four options with [E]dit

[V]iew  : Displays the set of data currently in memory.
[I]nsert: Allows you to insert a new point AFTER the one you will specify.
[D]elete: Allows you to delete any point.
[M]odify: Allows you to enter new values of X & F(X) for a specified point. If
you choose the wrong number just hit  C/R at the X and F(X) prompt to keep the
old values.

To end [E]dit just hit C/R or ESC at the options prompt.

OPTION [L]sqFit:  Calculates the best fitting polynomial up to order 14 by the
method of least squares.  The only  input that is required is the order of the
polynomial the program  takes care of the  rest.  At the present time, to find
the best fit requires inversion of  up to a  14x14 matrix with  a Gauss-Jordan
scheme that uses full pivoting.  However, the  matrix that must be inverted is
usually highly illconditioned or near singular and can cause a fatal execution
error.  A numeric overflow error #07 is the only one that will currently cause
PwrStar to terminate  without warning so  make sure  your input data are saved
before running this option and start with the lowest order polynomial then you
may increase the order  one step at a time.  The overflow error is inherent to
the  Gauss-Jordan  algorithm.  The 8087 version reduces the roundoff error and
therefore allows a larger order curve fit to your data before numeric overflow
occurs.  The 8087 version also runs 5 - 10 times faster than the 8088 version.

Note that Version 1.35 now normalizes your X, F(X) input before performing the
least squares fit by dividing the X values by their average so that  Xn=X/Xavg
and the F(X) by the corresponding average so Fn(Xn) F(X)/Favg.  This  mod  was
required to increase the numerical stability of the matrix inversion algorithm
and reduce susceptibility to crashes for ill-conditioned data.

To use the Fn(Xn) equation now calculated by  the program, first devide your X
input value by the Xavg value given by  PwrStar, then plug into given equation
and multiply resulting Fn(Xn) by the  Favg value given by  PwrStar to get F(X)
at any X.  The interpolation option  [I] does this for you automatically.

The program prints out: Pt, X, F(X), F(X) Calc, RESID where:
Pt       : point number
X        : input value of independent variable
F(X)     : input value of dependent variable
F(X) CALC: Value of dependent variable calculate at X from the polynomial fit
RESID    : Residual error = F(X) CALC - F(X)

You also get the values A1...A11 for the polynomial coefficients and estimates
of how much error there may be in each one where: F(X) = A1 + A2*X +A3*X*X . .

Finally, the correlation coefficient gives you a direct indication of how well
the polynomial fits the data with 1.0 being an exact fit.

NOTE:  After a correlation of 1.0 is achieved,  you get NO FURTHER ACCURACY in
the curve fit since IT IS ALREADY EXACT.  PWRSTAR will allow higher order fits
even though a correlation of 1.0 was achieved with  a lower fit.  However, the
numerical method eventually becomes unstable  due to roundoff error, A MACHINE
LIMITATION, and PWRSTAR will crash.  THERE NOTHING WRONG WITH THE PROGRAM!

NOTE:  The maximum order of the polynomial will one less than the total number
of data points available.  Therefore for 8 points a  maximum 7th order fit can
be used.

OPTION [G]raph:  The purpose of this option is to provide  a QUICK look at how
well the curve fits the data and spot any  problems with  input.  PwrStar will
calculate the proper minimum and maximum for  each axis to maximize use of the
screen.  To use the default values hit  C/R after the defaults are printed for
each axis.  You may also  enter your own axis scale by typing [Y]es when asked
to change?  For each axis  minimum and maximum, hitting  C/R uses the  default
values.  The following values are printed at the bottom of the screen:

Horizontal Axis
Left  = Minimum value of X axis      dx = Value of each X axis tick mark
Right = Maximum value of X axis

Vertical  Axis
Bottom = Minimum value of F(X) axis  dx = Value of each F(X) axis tick mark
Top    = Maximum value of F(X) axis

Starting with version 1.35 you now  have  an  additional  graphics input screen
after selecting the graph option.

SubOption [G] or [C/R]: Generates the plot as with previous versions.

SubOption [H]orz-Grid : Adds a horizontal grid to the plot.

SubOption [V]ert-Grid : Adds a vertical   grid to the plot.

SubOption [B]oth      : Adds a vertical and horizontal grid to the plot.

SubOption [N]one      : Removes grids.

SubOption [D]ense     : Changes grid density to every DX and DY axis mark.

SubOption [S]parse    : Changes grid density to every 5th DX and DY axis mark.

SubOption [T]itle     : Allows entry of plot title up to 69 characters long.

To get  a graphics dump  of the screen, you  must first  run GRAPHICS.COM from
your DOS diskette or GRAFTRAX.COM  prior  to running PwrStar.  To get a screen
dump run  [G]raph and  hit the  Shift-PrtScr combination when the  bell sounds
indicating  that PwrStar  is waiting  for you to  make your copy.  Hitting C/R
instead will get you back to the Command Menu.

**** YOU MUST HAVE A GRAPHICS ADAPTOR INSTALLED FOR THIS OPTION TO WORK *****

OPTION [I]nterpolate:   Is used after data have been  entered and a polynomial
fit defined.  Hitting [I]nterpolate  will have PwrStar prompt  you for the new
independent variable X and it will calculate  a new value  of F(X) and ask for
more (Y/N)?  Hitting C/R  or Y makes PwrStar ask for another value and hitting
ESC or N sends it back to the Command Menu.

***** BE VERY CAREFUL WHEN EXTRAPOLATING ******  If the value of X to get F(X)
that you request is not within the bounds ( Xmin <= X <= Xmax ) of  your input
data, then the result could be nonsense.  Before extrapolating use [G]raph  to
evaluate how the  function  you've selected  behaves beyond  the range of your
input where you wish to extrapolate for F(X).   You do this by  specifying the
minimum and maximum values of the X and F(X) axes on the graph.

Starting with version 1.35 you now have an  additional option if your computer
has the Color/Graphics Adaptor (CGA) installed.  After selecting [I]nterpolate
you will be asked to select [M]anual or [G]raphic interpolation.

SubOption [M]anual : PwrStar will prompt you for X and calculate F(X).

SubOption [G]raphic: Pwrstar will draw the  data point, fitted line, and then
turn  on a "Cross-Hairs blinking cursor" near  the center of the screen.  The
X and F(X) values of the curve are displayed on top of the plot.  You can now
use the Left & Right Arrow keys to interactively change X and get a new value
of F(X) displayed. Using Ctrl-Left Arrow or Ctrl-Right Arrow moves the cursor
around faster.

Option [Z]ap:  Provides smoothing of X, F(X) or both by using a variable point
number smoothing average.  The only  restrictions are that the  moving average
must be an odd number and equal to or less than the total number of points.

Option [S]ave:   Takes whatever  data are  currently in memory and  saves to a
user specified disk file.  This  option should  be run immediately  after data
are input from the keyboard to guard against GREMLINS.   When selecting [S]ave
you will be asked for the name of the disk file.  If it already exists you may
then [O]verwrite, [A]ppend to it, or hit C/R or ESC to  return  to the Command
Menu.  If you use the [A]ppend  option, you  must then modify the file with an
editor because only the first input set will be used by PwrStar.

OPTION [P]rint:  Takes whatever data are currently  in memory and sends to the
printer.

OPTION [H]elp:  Displays this file interactively.

OPTION [Q]uit:  Ends execution.

We are anxious to  hear  from you  how to  make  PwrStar  more  useful to  you.
Please  mail  all comments and suggestions through CompuServe EasyPlex mail to
#76167,327 or to:

                          HyperStuffWare
                       5019 Silver Arrorw Dr
                       Dayton, oh 45424-4813


COMPUTERS

So far, PwrStar will run on: IBM-PC/XT/Jr, Zenith 148/150, Sanyo MBC-555,
IBM-AT, Compaq II, Leading Edge, Toshiba 1100+

KNOWN PROBLEMS

Hitting the NumLock key on the Sanyo MBC-555 when PwrStar expects an input will
crash the program - so make sure NumLock is set before running PwrStar.

VERSIONS of PwrStar

 1.02 : First version released 15 Jun 1986

 1.10 : Corrected pesky bug that chomped part of the screen when ending the
        program by hitting  Ctrl-Break.  The  [D]ir option  now defaults to
        *.* on the default drive.   Finally, PwrStar  now clears the screen
        and returns to Black & White when it terminates. 30 June 1986

 1.11 : Modified for Leading Edge PC.   PwrStar now determines what type of
        graphics adapter is installed (color or monochrome) and selects the
        colors accordingly. 02 July 1986

 1.12 : Improved graphics display. 16 Aug 1986

 1.20 : Improved numerical stability of algorithm so PwrStar is unlikely to
        crash when selecting higher order fits; it  was before.  My special
        thanks go to  Mr Lee Holman for identifying the problem and getting
        me to think of a solution.   Mr Holman got  the new version back by
        return mail.  10 September 1986

 1.21 : Increased the  number of  input  values to 300 and added check that
        prevents trying to plot integer values not in -32768 to 32767.
        22 November 1986

 1.30 : Corrected bug that was generated after modification which normalized
        the input data for greater accuracy.  Also changed plotting logic so
        that actual data and fitted curve values are  plotted instead of the
        normalized values used in versions  1.20 and 1.21.  This option also
        added a smoothing option based on a variable moving average method.
        24 January 1987

1.31 : Changed logic when using [L]sqFit option.  Before, after [L]sqFit was
       selected, the  user could  read a  new file or modify the data and if
       the [G]raph  option was  selected, PwrStar would  erroneously display
       the new data and  the  old function fit.  Now, selecting the [F], [K],
       or [E] options automatically  requires the user to run the [L] option
       if a graph of the curve with the new  data is desired.  This mod also
       changed the logic  used to write the results  to the screen after the
       [L] option is selected.  28 March 1987

1.32 : Minor  logic changes  to the  [Z]ap smoothing option and [G]raph auto
       scale options.   Once the [G]raph  option is  run,  the  caculated or
       user provided minimum  and  maximums are retained.  Entering new data
       or modifying existing data will  reset the scales to those calculated
       by the [G]raph option.  The blinking red user prompt was also changed
       at the request of a registered user.  The [G]raph colors were changed
       to white only to fix contrast problems for EGA users.

1.35:  Minor logic changes  to fix [K]eyboard entry bug generated in version
       1.32.   Added dense or sparse  grids (horizontal and vertical) to the
       [G]raph option.  Also added interactive  [G]raphics option when inter-
       polating data.  14 September 1987

1.36   At the request of registered users,  the [K]eyboard input option was
       expanded  to include an [A]utomatic prompt  and entry of data points
       without having to enter the point number for each point.
       27 September 1987

1.37   Corrected  minor  bug which caused a crash  when viewing a graph and
       hitting a key with an  extended scan code (such as left arrow) while
       the numlock was in the numeric position.  01 November 1987

1.38   Corrected minor bug which caused problems on AT class machines running
       DOS 3.X while trying to save keyboard entered data before running  the
       [L]sqFit option.  07 December 1987

2.00   Converted PwrStar to Turbo Pascal Version 4.0 and corrected a few minor
       bugs.  This update also added graphics support  for  the CGA, EGA, VGA,
       Hercules, and  other drivers supported by Turbo 4.0.  Two versions  are
       now shipped: PwrStar.88 is the 8088/8086 executable file, PwrStar.87 is
       the 8087 executable file.  18 January 1988

2.11   Corrected minor bug generated in version 2.10.  The  bug  occurred only
       when reading from a saved file where F(X) CALC was negative.
       28 February 1988

2.15   Incorporated graphics device drivers into executable file  to eliminate
       the need to keep the Borland *.BGI files on the same disk.
       12 September 1988

2.16   Improved implementation of numeric coprocessor version which  now runs 5
       to 10 times faster than the 8088 version.  The file  sizes decreased and
       a bug was fixed which kept eating available memory after each call  to a
       plotting option was made.  The 8088/80286 version is now shipped in file
       PwrStr88.EXE and the 8087/80287 version in file PwrStr87.EXE.
       14 September 1988

2.17   Corrected minor bug which occurred when reading back a file where F(X)
       was negative.  24 September 1988



                                           THANKS FOR USING PWRSTAR

                                           Hank Hernandez
                                           CompuServe #76167,327

                                           HyperStuffWare
                                           5019 Silver Arrow Drive
                                           Dayton, Ohio 45424-4813